<html>
<head>
<title>
BTrace Developer's Guide
</title>
</head>
<body>

<h1>BTrace Developer's Guide</h1>
<p>
<b>BTrace</b> is a safe, dynamic tracing tool for Java. Please
refer to <a href="usersguide.html">user's guide</a> for BTrace usage
information.
</p>

<h3>BTrace Development Tools</h3>

<p>
<ul>
<li>BTrace requires JDK 6 or above. 
<li>BTrace can be built using <a href="http://ant.apache.org/">ant</a> or
<a href="http://www.netbeans.org">NetBeans IDE</a>.
</ul>
</p>

<h3>BTrace Components</h3>

<p>
BTrace accepts a tracing program written in (subset) of
the Java programming language. BTrace compiles the trace class
into bytecode and submits the same to a java.lang.instrument agent that
runs inside the target program. The BTrace agent is dynamically 
loaded into the target program if it is not already loaded (using
"attach-on-demand" API).
</p>
BTrace Components:
<ul>
<li><b>BTrace Client Tool</b> - compiles, validates and submits BTrace program to
BTrace VM agent. And receives trace messages and prints to stdout.
<li><b>BTrace java.lang.instrument Agent</b> to bytecode instrument classes
and hotswap them. Also, this agent verifies the bytecodes of BTrace
class for safety [read-only, boundedness] rules. This way we don't need 
to trust the client to enforce the safety rules at compile time.
<li><b>Wire Protocol</b> between the client and the agent.
</ul>
<h3>

<h3>BTrace Packages</h3>
<ul>
<li><b><code>com.sun.btrace.agent</code></b>. This package contains
classes for BTrace's <b><code>java.lang.instrument</code></b> agent.
This agent uses simple socket protocol to communicate with the client.
Multiple BTrace clients are supported. For each client, an instance
of com.sun.btrace.agent.Client is created.
<li><b><code>com.sun.btrace.annotations</code></b>. This package
contains annotations and enumeration classes used by BTrace author
as well as agent to specify/infer "probed locations" of the traced
program. These classes are loaded by bootstrap loader (agent
adds classes containing these classes to bootstrap path).
<li><b><code>com.sun.btrace.client</code></b>. This package contains
BTrace client tool main class.
<li><b><code>com.sun.btrace.dtrace</code></b>. This package contains
BTrace and DTrace integration classes. The classes that wrap DTrace/Java
API are here. Please refer to /use/share/lib/java/javadoc/dtrace for DTrace/Java
API.
<li><b><code>com.sun.btrace.comm</code></b>. This package contains
wire protocol messages between BTrace agent and client tool. BTrace
agent and client communicate by object serializing the instances of
Message classes.
<li><b><code>com.sun.btrace.compiler</code></b>. This package
has classes for compiling a BTrace program into bytecode after
safety verification. Because BTrace accepts subset of Java, it uses
javac's APIs (JSR 199 - compiler tool API, JSR 269 - Annotation 
Processing API and javac Tree API to access AST of compiled Java 
program) to compile and enforce BTrace safety rules.
<li><b><code>com.sun.btrace.resources</code></b>. This package contains
error messages resource used by BTrace compiler and bytecode verifier.
<li><b><code>com.sun.btrace.runtime</code></b>. This package contains
various bytecode instrumentation classes used by BTrace. These 
instrumentation classes use <a href="http://asm.objectweb.org">Objectweb's ASM</a> 
package to do actual class file parsing and writing. ASM version 3.0
is used. This package contains BTrace bytecode verifier and jvmstat reader as well.
<li><b><code>com.sun.btrace</code></b>. This package contains classes loaded
by bootstrap loader (agent adds classes containing these classes to bootstrap path).
<code>com.sun.btrace.BTraceUtils</code> class contains built-in "functions" that can be called
by any BTrace program (these are read-only and bounded methods can
be called by trace program). <code>com.sun.btrace.BTraceRuntime</code> class contains 
per-client state for each BTrace client and helps implementing certain methods
of BTraceUtils. Also, BTraceRuntime makes sure that BTrace agent's own
method invocations and BTrace built-in "function" calls are not
traced [there by leading to infinite recursion!].
</ul>

<h3>BTrace jar files</h3>

<ul>
<li><b>btrace-boot.jar</b> - loaded by bootstrap loader in the traced
JVM. Contains BTrace annotation classes in <b><code>com.sun.btrace.annotations</code></b>
package and classes in <b><code>com.sun.btrace</code></b> package.
<li><b>btrace-agent.jar</b> - contains classes for java.lang.instrument
agent and instrumentation classes. This uses <b><code>asm-3.0</code></b>
jar for instrumentation and <b><code>tools.jar</code></b> for reading
jvmstat counter values [<b><code>sun.jvmstat.monitor</code></b> classes].
<li><b>btrace-client.jar</b> - contains BTrace client classes. This
uses <b><code>tools.jar</code></b> for javac's classes.
</ul>

<h3>BTrace "To Do"s</h3>
<ul>
<li>Remove instrumentation when a client leaves tracing session.
Right now, we "disable" trace calls when a BTrace client leaves
the session. It would be better to remove the instrumentation and
re-hotswap the classes to avoid the "disabled" calls completely.
</ul>

<h3>Debugging BTrace</h3>
<p>
BTrace can be debugged by setting few System properties. All these properties are 
set at the BTrace client.
<ul>
<li><b><code>com.sun.btrace.debug</code></b> - this boolean valued property makes 
BTrace to print debug messages (set at client - but debug mode is propagated
to BTrace agent as well).
<li><b><code>com.sun.btrace.dumpClasses</code></b> - this boolean valued property
may be set to force BTrace agent dump every .class that is
intrumented.
<li><b><code>com.sun.btrace.dumpDir</code></b> - this is a String valued property
that sets the directory where the instrumened .class files are dumped.
</ul>
It is better to run the traced JVM with <b><code>-Xverify:all</code></b> to force 
bytecode verification of all classes. This is to make sure that BTrace does not produce
bad classes thereby crashing the JVM. After dumping instrumeted classes, it is possible
(offline) analyze those using <b>javap</b> tool. The BTrace action methods look like 
the form: "btrace$&lt;trace-class-name&gt;$&lt;trace-action-method-name&gt;" - where "."s 
in the trace class name are replaced by "$".
</p>

<h3>Known Issues and Limitations</h3>

<ul>
<li><b>BTrace requires JDK 6</b>. There are API dependencies [for example, javac's new APIs].
And BTrace uses certain recent changes with java.lang.instrument and hotswap. In particular,
<b>BTrace adds private methods while hotswapping classes</b>. This feature (of
adding private methods while hotswapping classes) is <b>not</b> available in earlier 
JDK versions. Also, retranformantion is used to avoid fetching .class bytes from
the file system. Again, this is a new feature of java.lang.instrument API since JDK 6.
</ul>

</body>
</html>
